
__________________

Creator user guide
__________________


User, please note
=================

Creator is Shareware. It is not free software. You may, however, freely use it
for a 30 day trial period. After this trial period, you must decide whether or
not you want to continue using it. If you do, you must register your copy of
Creator (refer to 'Registering' for details). If you don't, you must delete
your copy of Creator and can never use it or try it out again.

Please respect the rules of Shareware. Shareware is a 'try before you buy'
method of distribution that provides you with excellent software at a very low
price. Programs like Creator have cost an awful lot of time and effort to
develop, will serve you well for a long time, and will cost you very little
money (well below what is reasonable in a commercial sense).

Copyright notice
================

The copyrights (c) of this program belong to John Kortink. All rights are
reserved.

You may not make changes to this program (except for documented configuration
changes). If you distribute it, you may only distribute the complete and
unchanged original copy (as you first received it). You may distribute this
program freely, but must obtain written permission from me if it is to be
distributed as part of, or alongside, any product that is meant to generate
profits. This program is provided 'as is'. Fitness of this program for any
particular purpose is not implied. Using it is entirely at your own risk.


//
//
// Introduction
//
//

Creator is a bitmap image convertor.

It is able to convert a wide variety of bitmap image formats and/or change the
number of colours in an image. Creator uses sophisticated algorithms to ensure
high quality results.

In addition to this, you will find Creator to be *fast*. Most of Creator has
been written in ARM assembly code, the rest has been written in C++. In
addition, some ported C code is used for JPEG and PNG conversion.

You may have noticed that the latest incarnations of Translator, one of my
other applications, provide a superset of Creator's functionality. Creator
still exists because for plain image format conversion it is simpler and
quicker to use.


//
//
// Compatibility
//
//

Creator should be compatible with :

- RISC OS 3.1 and later
- ARM 2 and later processors (26-bit architectures only)


//
//
// Using Creator
//
//

On Creator's iconbar menu the usual 'Info' and 'Quit' icons can be found.

In addition, 'Options...' gives access to the 'Options' window and 'Choices'
gives access to the 'Choices' menu. Both the 'Options' window and the 'Choices'
menu are described below.


//
//
// Converting an image
//
//

Simply drag the image file to Creator's icon. Creator will complain if it
cannot recognize the image format.

The 'Convert image' window will appear, displaying the relevant details of the
input image and enabling you to specify the output image format. The 'Convert
image' window is described below.


//
//
// The 'Convert image' window
//
//

In this window, you will find two parts, called 'Input image' and 'Output
image'.

The 'Input image' part refers to the image file you dragged to Creator, and
shows details of the input image.

The 'Output image' part refers to the image file you are going to save, and
allows you to specify the format of the output image.

The format of the output image may be chosen as follows :

- 'Format' allows you to choose the image format.
- 'Colours' allows you to specify the number of colours to be retained in the
  image, by bits per pixel (the number of colours is '2 ^ bits per pixel'). The
  choices presented depend on the chosen image format. If the writable field to
  the right of the menu icon is not shaded, you may also specify a more precise
  number of colours if you wish.
- 'Compression' allows you to choose the compression method used. The choices
  presented depend on the chosen image format.
- 'Filename' allows you to specify the leafname of the image to be saved.

The 'Colours' field deserves some further explanation. This is displayed as 'x
bit r:g:b type', where 'x' is the number of bits per pixel (referred to below
as 'bpp'), 'r', 'g', and 'b' are the number of bits of accuracy in a pixel
colour of red, green, and blue respectively, and 'type' is the pixel colour
type. There are essentially two pixel colour types :

- The 'palette' or 'grey' type indicates that pixel values are not pixel
  colours themselves but indices into a pixel colour lookup table (called a
  'palette'). The 'grey' pixel type also indicates that all palette colours are
  shades of grey. If 'fixed' appears in the type, the palette is always fixed
  (in all other cases Creator calculates an optimal palette).
- The 'true' pixel type indicates that pixel values directly represent pixel
  colours. Therefore, 'x' is always the addition of 'r', 'g' and 'b'.

Saving the image may or may not need colour quantization, colour dithering
and/or colour remapping algorithms to be applied. Creator applies the required
algorithms automatically. The accuracy of the calculations performed by the
algorithms may be changed, if needed. Refer to the discussion of the
'Quantization' and 'Dithering' parts of the 'Options' window.

Colour quantization is used whenever a 'superset' of colours (used in the input
image) needs to be reduced to a smaller 'subset' of colours (to be used in the
output image). The colour quantization algorithm calculates the subset of
colours that best represents the superset of colours. Colour quantization is
only used for palette colour output images. The colour quantization algorithm
used is known as 'Heckbert median cut'.

Colour dithering is used when the number of colours in the output image is less
than that in the input image, or when any of the number of bits per r/g/b in
the output image colours is less than that in the input image colours, or when
the output palette is fixed. In all these cases, some or all of the input image
colours do not have an exactly matching colour in the output image, and so, for
these colours, the 'closest' output image colour is used. Per pixel, the colour
dithering algorithm then 'diffuses' the error (the difference in colour) by
slightly changing the colours of neighboring pixels. This makes the errors less
visible to the human eye. The colour dithering algorithm used is a 'zizag'
variant of the widely known and used Floyd-Steinberg algorithm.

Colour remapping is used whenever the colour quantization algorithm is used,
and it finds that the number of different colours actually used in the input
image is less than or equal to the number of available output image colours.
In this case, the output image palette simply consists of all actually used
input image colours, and all that is needed is 'remapping' of the input image
colours to their respective output image colours. An exact copy of the input
image results. For example, it is not uncommon to encounter 24 bpp 'true
colour' image files in which only 256 colours (or even less) are actually used.
This can happen if someone, somewhere, sometime, for whatever dim reason, has
'promoted' an 8 bpp palette colour image to 'true colour'. In these cases, the
original palette colour image is exactly recreated, usually saving space.

Creator does the right thing if the output palette turns out to be all grey
(which usually only happens when the output format requires a fixed grey
palette, e.g. PBMPlus 8 bpp or JPEG 8 bpp). In this situation, the colour
dithering algorithm used is unsuitable if the input image is in colour, because
colours are impossible to approximate well with just grey values, resulting in
a bad quality output image. A special 'grey only' dithering algorithm is used
instead, which gives much better results. The 'Dithering' setting in the
'Options' window has no effect if this algorithm is used.

After making all your choices, you can save the image by dragging the filetype
icon. This will result in the image being saved to the directory that the icon
was dragged to, using the leafname specified under 'Filename'.


//
//
// The 'Options' window
//
//

In this window, you will find four parts, called 'Load options', 'Save
options', 'Quantization' and 'Dithering'.

The 'Load options' part allows you to specify 'load options' for some image
formats, which influence the way images are loaded. In most cases load options
can be left at their default settings. Refer to 'Supported image formats
(detailed)' for information on specific load options.

The 'Save options' part is similar to the 'Load options' part, except that
these options influence the way that images are saved.

The 'Quantization' part allows you to select the accuracy with which colour
frequencies are determined during colour quantization (refer to the discussion
of 'Save'). A higher number of bits for 'Red', 'Green' or 'Blue' will increase
the accuracy with which the corresponding colour component is handled. Note
however that selecting more than the default of 5 bits per colour component
results in only very marginal and mostly unnoticable differences in image
quality. Also note that selecting less than 5 bits is not really recommended
except for the possible entertainment value that the resulting images provide.
Also note that the memory requirements for the quantization tables double with
every bit added to the total number of bits. The default setting of 5 bits per
colour component (15 bits total) requires around 128 KB of processing memory.

The 'Dithering' part allows you to select the accuracy of the colour mapping
tables used during colour dithering. Comments similar to the comments under
'Quantization' apply. 15 bits, again, translate to 128 KB.


//
//
// The 'Choices' menu
//
//

In this menu you can manipulate Creator's 'choices'.

- 'Save' will save the current choices.
- 'Load' will load the saved choices.
- 'Default' will load the default choices.
- 'Kill' will discard the saved choices.

When Creator starts up it loads the saved choices, or the default choices if no
choices were saved.

The choices consist of all the settings in the 'Options' window.


//
//
// Supported image formats (overview)
//
//

Creator can read the following image formats (in alphabetical order) :

- AIM
- BMP
- CadSoft
- Clear
- Degas
- Draw
- GIF
- IFF
- ImageIO
- IMG
- Irlam
- JPEG
- MacPaint
- MTV
- PBMPlus
- PCX
- Pineapple
- PNG
- QRT
- Sprite
- TIFF

Creator can write the following image formats (in alphabetical order) :

- BMP
- Clear
- GIF
- ImageIO
- JPEG
- PBMPlus
- PNG
- Sprite
- TIFF

The 'ImageIO' format is a special 'internal' format which is not meant to be
used outside Creator.

For more details about the image formats that Creator supports, see 'Supported
image formats (detailed)'.

For some image formats that Creator understands, you may specify a few special
settings to be used when loading or saving an image in that format. Refer to
the discussion of the 'Load options' and 'Save options' parts of the 'Options'
window.


//
//
// Supported image formats (detailed)
//
//

Following are brief details of all supported image formats.

Image format interpreters are usually complete, but may, in some cases, lack
support for some particular subformats. All image format interpreters have at
least been tested successfully on all sample images I could find, and have been
verified as well as possible against documentation available to me. Generally,
if Creator encounters formats or subformats that cannot be recognized or are
not supported, it will give up gracefully and provide an indication of why it
has failed.

AIM
===
- Origin
  Acorn machines. !AIM (Archimedes Image Manager) program.
- Colours
  8 bpp 8:8:8 grey
- Compression
  none
- Recognition
  filetype &004
- Miscellaneous
  Resolution is always 256 x 256 pixels.

BMP
===
- Origin
  IBM compatible machines. Microsoft Windows operating system.
- Colours
  1 bpp 8:8:8 palette
  4 bpp 8:8:8 palette
  8 bpp 8:8:8 palette
  24 bpp 8:8:8 true
- Compression
  none
  runlength
- Recognition
  filetype &69C
  'BM' at offset &0

CadSoft
=======
- Origin
  Acorn machines. Millipede Prisma display board.
- Colours
  8 bpp 8:8:8 palette
- Compression
  none
  runlength
- Recognition
  filetype &69A
  'MILLIPEDE' at offset &10

Clear
=====
- Origin
  Acorn machines. !Translator program and several hardware vendors' programs.
- Colours
  1,2,3,4,5,6,7,8 bpp 8:8:8 palette
  24 bpp 8:8:8 true
- Compression
  none
- Recognition
  filetype &690

Degas
=====
- Origin
  Atari machines. Degas and other programs.
- Colours
  1,2,4 bpp 3:3:3 palette
- Compression
  none
  runlength
- Recognition
  filetype &691

Draw
======
- Origin
  Acorn machines. Acorn defined native vector image format.
- Colours
  24 bpp 8:8:8 true
- Compression
  none
- Recognition
  filetype &AFF
- Load options
  'X*', 'X/', 'Y*' and 'Y/' specify scaling. Scaling is by 'X*' divided by 'X/'
  horizontally, and by 'Y*' divided by 'Y/' vertically.
- Miscellaneous
  Only available on machines running RISC OS 3.60 or higher.

GIF
===
- Origin
  Various machines. Graphics Interchange Format, devised by and copyright of
  Compuserve Incorporated.
- Colours
  1,2,3,4,5,6,7,8 bpp 8:8:8 palette
- Compression
  12-bit LZW
- Recognition
  filetype &695
  'GIF87a' or 'GIF89a' at offset &0
- Miscellaneous
  When reading, any GIF89a extensions are skipped and ignored. When writing,
  GIF87a format is always used.
- Save options
  'Interlace' defines whether or not an interlaced image is saved. 'Interlace
  = Yes' will save an interlaced image, 'Interlace = No' won't.

IFF
===
- Origin
  Various machines. Interchange Format File, devised by Electronic Arts.
- Colours
  1,2,3,4,5,6,7,8 bpp 4:4:4 palette
  1,2,3,4,5,6,7,8 bpp 8:8:8 palette
  12 bpp 4:4:4 true
  24 bpp 8:8:8 true
- Compression
  none
  runlength
- Recognition
  filetype &693
  'FORM' at offset &0 and 'ILBM' at offset &8

IMG
===
- Origin
  Atari and IBM compatible machines. Digital Research GEM programs.
- Colours
  1 bpp 8:8:8 grey
- Compression
  various methods
- Recognition
  filetype &692

Irlam
=====
- Origin
  Acorn machines. Irlam video digitiser.
- Colours
  24 bpp 8:8:8 grey
- Compression
  none
- Recognition
  filetype &69B
  'Irlam' at offset &0

JPEG
====
- Origin
  Various machines. Joint Photographic Expert Group, the actual format is
  called JFIF (JPEG File Interchange Format), devised by C-Cube Microsystems.
- Colours
  8 bpp 8:8:8 grey
  24 bpp 8:8:8 true
- Compression
  Baseline JPEG
- Recognition
  filetype &C85
  &FF, &D8 at offset &0
- Load options
  'Float DCT = No' uses 'fast' integer DCT (Discrete Cosine Transform) code.
  'Float DCT = Yes' uses slightly more accurate but 'slow' floating point DCT
  code. In practice, both option settings nearly always result in the same
  image quality.
- Save options
  'Quality = xx', where xx = 0..100, sets the quality level. 100 is best
  quality, lowest compression. 0 is worst quality, highest compression.
  'Optimize' switches on/off compression optimization (switching it on
  results in somewhat smaller files but also uses more processing time).
  'Optimize = Yes' switches on compression optimization. 'Optimize = No'
  switches it off.
- Miscellaneous
  - Processing code is in C. Acknowledgements :
    - Compiled with GCC for RISC OS 2.95.4, (c) 1996-2001 Nick Burrett.
    - Uses IJG JPEG library 6b (27 Mar 1998), (c) 1991-1998 Thomas G. Lane
      I am required to state that 'This work is based in part on the work of
      the Independent JPEG Group'.

MacPaint
========
- Origin
  Apple MacIntosh machines. MacPaint program.
- Colours
  1 bpp 8:8:8 grey
- Compression
  runlength
- Recognition
  filetype &694
  'PNTG' at offset &41
- Miscellaneous
  Resolution is always 576 x 720 pixels.

MTV
===
- Origin
  Various machines. MTV ray tracer.
- Colours
  24 bpp 8:8:8 true
- Compression
  none
- Recognition
  filetype &699

PBMPlus
=======
- Origin
  Unix machines. Portable Bit Map set of conversion programs, devised by Jef
  Poskanzer.
- Colours
  1,2,3,4,5,6,7,8 bpp 8:8:8 grey
  24 bpp 8:8:8 true
- Compression
  none
- Recognition
  filetype &69E
  'Px' at offset &0, where x = 1,2,3,4,5,6
- Miscellaneous
  Cannot save 2..7 bpp 8:8:8 grey.

PCX
===
- Origin
  IBM compatible machines. ZSoft PC Paintbrush program.
- Colours
  1,2,4,8 bpp 8:8:8 palette
- Compression
  none
  runlength
- Recognition
  filetype &697

Pineapple
=========
- Origin
  Acorn machines. Pineapple Software video digitiser.
- Colours
  16 bpp 5:6:5 true
- Compression
  none
- Recognition
  filetype &696
  'FSIfile' at offset &0
- Miscellaneous
  Resolution is always 512 x 256 pixels.

PNG
===
- Origin
  Various machines. Portable Network Graphics format, initially designed to
  impove on and fully replace GIF, since GIF's compression algorithm poses
  patent problems since 1995. Forget GIF, use PNG (compresses better too !).
- Colours
  1,2,4,8 bpp 8:8:8 palette
  1,2,4 bpp 8:8:8 grey
  8 bpp 8:8:8 grey with optional alpha channel
  16 bpp 16:16:16 grey with optional alpha channel
  24 bpp 8:8:8 true with optional alpha channel
  48 bpp 16:16:16 true with optional alpha channel
- Compression
  Deflate
- Recognition
  filetype &B60
  137, 80, 78, 71, 13, 10, 26, 10 at offset &0
- Save options
  'Interlace' defines whether or not an interlaced image is saved. 'Interlace
  = Yes' will save an interlaced image, 'Interlace = No' won't.
- Miscellaneous
  Reader supports all formats, but :
  - 16 bpp 16:16:16 grey is 'stripped' to 8 bpp 8:8:8 grey.
  - 48 bpp 16:16:16 true colour is 'stripped' to 24 bpp 8:8:8 true colour.
  - Alpha channels and transparency cause pixel colours to be recalculated
    against a background colour (black if not specified in PNG file).
  - Processing code is in C. Acknowledgements :
    - Compiled with GCC for RISC OS 2.95.4, (c) 1996-2001 Nick Burrett.
    - Uses libpng 1.2.1, (c) 1998-2001 Glenn Randers-Pehrson.
    - Uses zlib 1.1.3, (c) 1995-1998 Jean-loup Gailly and Mark Adler.

QRT
===
- Origin
  Various machines. QRT ray tracer.
- Colours
  24 bpp 8:8:8 true
- Compression
  none
- Recognition
  filetype &698

Sprite
======
- Origin
  Acorn machines. Acorn defined native pixel image format.
- Colours
  1,2,4,8 bpp 4:4:4 palette
  1,2,4,8 bpp 8:8:8 palette
  15 bpp 5:5:5 true
  24 bpp 8:8:8 true
- Compression
  none
- Recognition
  filetype &FF9
- Load options
  'Default palette' defines the palette to use when palette colour sprites
  without a palette are loaded. If the mapping of the bpp of the input to the
  corresponding mode is thought of as 1,2,4,8 bpp --> mode 18,19,20,21, then
  'Default palette = WIMP' will use the default WIMP palette for the
  appropriate mode, and 'Default palette = Mode' will use the default mode
  palette (as after a MODE command outside the desktop).
- Save options
  'Sprite type' defines the sprite type to save. It only affects the mode
  number saved in the sprite file. 'Sprite type = Default' will save old type
  sprites for 4:4:4 palette colour input, else new type sprites. 'Sprite type
  = Force old' will always save old type sprites. 'Sprite type  = Force new'
  will always save new type sprites.
- Miscellaneous
  Sprite masks are always ignored. Old type 8 bpp 4:4:4 sprites always have
  the standard fixed 256-colour palette and are actually saved without
  palette.

TIFF
====
- Origin
  Various machines. Tag Image File Format (that's 'Tag', not 'Tagged' as most
  people think !), devised by Aldus Corporation and Microsoft Corporation.
- Colours
  1,2,4,8 bpp 8:8:8 palette
  1,4,8 bpp 8:8:8 grey
  24 bpp 8:8:8 true
- Compression
  none
  PackBits
  12-bit LZW
  Modified Huffman
  Group 3 Fax
- Recognition
  filetype &FF0
  'II' or 'MM' at offset &0
- Save options
  'Endian' selects between saving in 'big endian' or 'little endian' format.
  The official TIFF docs recommend using 'big endian', although TIFF readers
  are required to handle both types. 'Prediction' selects whether or not
  'prediction' is used. If used, it is only in effect when the 'Compression'
  setting in the 'Save image' window is '12-bit LZW' and the 'Colours'
  setting is either '24 bit 8:8:8 true' or '8 bit 8:8:8 fixed grey'. Using
  'prediction' in these cases almost always results in a smaller output file.


//
//
// Registering Creator
//
//

This version of Creator is 'key locked'. It 'nags' when you convert an image.
When you register Creator, a key will be emailed to you, which, when installed,
will stop Creator nagging. Note that keys will be sent by email only. If you're
already registered, please email me to obtain a key, quoting the name and
address you used when you registered, how much you paid, and approximately
when.

You can register your copy of Creator by paying 15 Euro. If possible, email me
first for (possibly changed) details.

You can pay in one of the following ways, in order of preference :

- Online with PayPal

  Please pay 17 Euro total to cover PayPal costs.

  Go to (on Internet) :

  http://web.inter.nl.net/users/J.Kortink/home/software/creator/index.htm

  and follow the instructions.

  Alternatively, simply go to www.paypal.com, follow 'Send money', and pay to
  kortink@inter.nl.net.

- Sending bank notes

  Take a piece of paper, fold it, slip 15 Euro or 10 UKP (in banknotes only,
  please) in between, scribble your snail mail and email address on the paper,
  slip it in an envelope, stamp it, email me to obtain the address to send it
  to, and mail it.

Please note that I cannot accept ways of payment other than cash and PayPal.

As soon as your money arrives you are a registered user of Creator. This
entitles you to free and continued use of all current and future Shareware
versions of Creator.

Note that Creator is part of a two application package : Translator and Creator
(GreyEdit, which used to be a part of the package as well, is now freeware).
This means that when you register Creator, you are automatically registered for
Translator as well, for free.


//
//
// Epilogue
//
//

Updates of Creator (if any appear) will be made available by (in order of
preference) :

- World Wide Web : visit web.inter.nl.net/users/J.Kortink
- Electronic mail : email kortink@inter.nl.net

Enjoy !


John Kortink



